home *** CD-ROM | disk | FTP | other *** search
/ Aminet 7 / Aminet 7 - August 1995.iso / Tools / Docs / Player < prev    next >
Text File  |  1992-09-14  |  70KB  |  1,602 lines
  1.                                 MultiPlayer
  2.                                Version 1.32
  3.                        Copyright (C) 1992 Bryan Ford
  4.  
  5.  
  6.     NOTE: I have moved since version 1.31.  (Yes, that's right, I moved
  7. _again_. >:-\ )  See the end of this file for my new phone, E-mail, and
  8. temporary address.  (The permanent address is still the same.)
  9.  
  10.  
  11.                             License/Disclaimer
  12.                             ~~~~~~~~~~~~~~~~~~
  13.  
  14.     This program is free software; you can redistribute it and/or modify it
  15. under the terms of the GNU General Public License as published by the Free
  16. Software Foundation; either version 2 of the License, or (at your option)
  17. any later version.
  18.  
  19.     This program is distributed in the hope that it will be useful, but
  20. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22. for more details.
  23.  
  24.     You should have received a copy of the GNU General Public License along
  25. with this program; if not, write to the Free Software Foundation, Inc.,
  26. 675 Mass Ave, Cambridge, MA 02139, USA.
  27.  
  28.  
  29.  
  30.                                Introduction
  31.                                ~~~~~~~~~~~~
  32.  
  33.     Welcome to the most powerful, versatile, and user-friendly music player
  34. ever created on the Amiga!  As you will see, MultiPlayer has almost all the
  35. features you've seen in other music players, plus a great number that have
  36. never been implemented before in a music player.
  37.  
  38.     If you want to get full benefit from MultiPlayer you should at least
  39. scan through this whole documentation.  However, it is very easy to use, so
  40. feel free to take it for a test drive first.  If you're upgrading from a
  41. previous version of MultiPlayer, make sure you look at the History section
  42. near the end of this document to see what's new.
  43.  
  44.     One of the goals of MultiPlayer is to be as system-friendly as
  45. possible.  It multitasks well, it doesn't interfere with high-priority
  46. interrupts such as serial port interrupts, and it properly allocates audio
  47. channels so that the music doesn't conflict with other programs.  It takes
  48. full advantage of (and requires) Kickstart 2.0, and it isn't prone to
  49. "lose" notes on fast processors like most other players are.
  50.  
  51.     Another goal of MultiPlayer is to support a very diverse array of music
  52. formats.  MultiPlayer currently supports over twenty different common
  53. module formats, plus some special ones.  See 'Supported Formats' near the
  54. end of this document for a list of the module types MultiPlayer can play.
  55. (Not all of MultiPlayer's features are available with every module format,
  56. but MultiPlayer will at least play each format on the list.)
  57.  
  58.  
  59.  
  60.                          Updates and Registration
  61.                          ~~~~~~~~~~~~~~~~~~~~~~~~
  62.  
  63.     As stated above, MultiPlayer is free software, distributed under the
  64. GNU General Public License.  Therefore you may distribute it and its source
  65. code freely as long as you don't deprive others of that right.  (See the
  66. file COPYING-2 for all the details.)
  67.  
  68.     If you use MultiPlayer often, you may want to register with me to get
  69. telephone and E-mail support, cheap and easy updates, and other benefits.
  70. Registration is only $15 (must be in US currency).  This is not a "do this
  71. or your conscience or haunt you for the rest of your life" request; I'm
  72. only asking you to register if you want the extra benefits (listed below)
  73. that you will get by registering.  If you don't want them, then enjoy the
  74. program, but don't expect anything more from me.
  75.  
  76.     Unregistered users may order the latest version of MultiPlayer by sending
  77. $5 (US currency ONLY) to my address listed at the bottom of this document.
  78. I will send you full binaries and source code, including any non-commercial
  79. utilities required to compile it (not including compiler and other very
  80. large programs).
  81.  
  82.     Registered users get a little more flexibility.  To order the latest
  83. version by E-mail, simply send either $2 (bills are fine) or two disks to
  84. my address below, whichever is more convenient for you.  Registered users
  85. may also pre-order future updates: simply specify the latest version you
  86. already have along with your $2 or two disk, and I will send you the next
  87. version after that, as soon as it is released.  Registered users that don't
  88. pre-order and aren't on the Internet will receive announcements of major
  89. new updates of MultiPlayer (probably not every version, but every one that
  90. adds a significant number of new features).  Registered users on the Internet
  91. of course get announcements every version, and may request both binaries and
  92. sources directly from me by E-mail.
  93.  
  94.     Registered users are encouraged to keep in contact with me by mail,
  95. phone, or E-mail; whichever is most convenient for you.  I enjoy chatting
  96. with users, and while I don't have a great deal of time to work on
  97. MultiPlayer, I do try to implement all the requested features I have time
  98. for.  (Note that your particular most-wanted features are likely to be
  99. implemented sooner if you keep pestering me about them. :-) )  If you're
  100. going to call me by phone, note that I live on the west coast of the US,
  101. and you are most likely to get through to me in the early evening.  Mail
  102. and E-mail are of course welcome any time.
  103.  
  104.     I will NOT go out of my way to satisfy the wishes of unregistered
  105. users.  $15 is nothing compared to the registration fees of many Shareware
  106. programs of much lower quality.  If you don't think the above benefits are
  107. worth $15, then don't register - but don't expect me to provide any kind of
  108. support.
  109.  
  110.     If you have a bug fix or enhancement you've made to MultiPlayer and
  111. would like included in the official distribution, send it to me and I'll
  112. probably (no promises) incorporate it if it's reasonably clean, isn't
  113. likely to break lots of other things, seems at least slightly useful, is
  114. understandable, etc. If your added or modified code is more than about a
  115. screen or so long, I'll need a signed (paper) document releasing all rights
  116. to the code to me, for distribution under the General Public License.  (I
  117. hate legal details, but I would hate even more getting into stupid
  118. squabbles and/or lawsuits due to an oversight of these legal details.)  If
  119. your additions are quite extensive (i.e. a new module or something like
  120. that) and you work for a computer-related company of some kind, I may get
  121. nervous and require a signed disclaimer from your employer as well.
  122.  
  123.  
  124.  
  125.                               Acknowledgments
  126.                               ~~~~~~~~~~~~~~~
  127.  
  128.         Michael Sinz (CBM) for tips on the memory manager.
  129.  
  130.         Darren Schebek for lots of suggestions and ideas.
  131.  
  132.         Janne Saarme for lots of players and other stuff.
  133.  
  134.         Teijo Kinnunen for MED/OctaMED support and player code.
  135.  
  136.         Barry McConnell for lots of testing and suggestions, and
  137.             the 8-color icon.
  138.  
  139.         Maruku Burano for the module scrolltext idea (and some great
  140.             modules too of course :-) )
  141.  
  142.         Stefan Walter for S.I.M., without which debugging MultiPlayer
  143.             would have been a real nightmare.
  144.  
  145.         And most of all, to the talented people who create all the
  146.             wonderful music on the Amiga!
  147.  
  148.  
  149.  
  150.                                General Usage
  151.                                ~~~~~~~~~~~~~
  152.  
  153.     To start MultiPlayer, just type 'player' from the CLI or click on the
  154. icon from the Workbench and it will present the ASL filerequester to select
  155. a module from.  Note that you can select multiple modules at a time (as
  156. many as you want).  If you run MultiPlayer from the CLI, it automatically
  157. detaches itself, so there is no need to Run it.  (You can turn this feature
  158. off, however.)  You can also start modules playing immediately when
  159. MultiPlayer starts up.  See the section on 'Startup Options' for more
  160. information on starting MultiPlayer.
  161.  
  162.     While MultiPlayer is running there is normally a small window in the
  163. title bar displaying the name of the module that is currently playing (or
  164. just "MultiPlayer" if nothing is loaded).  You can click the close gadget
  165. to stop the music and terminate MultiPlayer.  (You can change this behavior
  166. in the Preferences window so that closing the main window simply hides the
  167. user interface, leaving MultiPlayer active in the background.)  The main
  168. MultiPlayer window has a zoom gadget near its right end.  If you click it,
  169. you will see a control panel that allows you to load different modules and
  170. gives access to some of MultiPlayer's more advanced features.
  171.  
  172.     If you have the xpkmaster.library (a freeware compression "supervisor"
  173. standard mostly by Dominik Mueller, Christian Schneider, and myself)
  174. installed in your system, MultiPlayer can automatically unpack modules that
  175. are packed using any format it can understand.  (This includes PowerPacker
  176. format, if you have the powerpacker.library installed as well.)
  177.  
  178.     If you start getting shaky when you see MultiPlayer's size (>90K),
  179. don't worry - thanks to a custom memory management and overlay system
  180. called Bovs, MultiPlayer uses only the memory it needs to do its job.  All
  181. of the module players are loaded only when needed, and any players not
  182. currently in use are unloaded on demand if the system runs out of memory.
  183. The parts of the program used to control MultiPlayer's various windows are
  184. also only loaded when they are needed (when the respective windows are
  185. open) and are freed as necessary.  Thus, generally only a small fraction of
  186. the program code is loaded at any one time.
  187.  
  188.     If you have tons of memory and don't want overlays, the registered
  189. release comes with a separate version of MultiPlayer ("Player.nov") that
  190. runs without overlays (like a normal program).  It generally uses about 50K
  191. more memory than the overlaid version does, but it can be compressed with
  192. PowerPacker or Imploder if you're short on disk space.  (Imploder *should*
  193. be able to compress the overlaid version of MultiPlayer, but it won't - I
  194. haven't figured out why.)
  195.  
  196.     For all you hackers (used in the positive meaning) that like to rip out
  197. every form of music imaginable, when you come across some obscure module
  198. format that nothing understands, don't despair.  There are several special
  199. formats built into MultiPlayer that you can use to easily interface it to
  200. any kind of module.  All you need is the module, some player code for the
  201. module (if the module doesn't already have embedded player code), and a
  202. little assembly language coding.  Details on all three formats are in the
  203. separate file 'GMOD.doc' (in the Programmers directory of the official
  204. MultiPlayer distribution).  If you are the author of a music composer
  205. program, you should also read this document and consider supporting the
  206. GMOD embedded-player module format in your program.  (It's not a music
  207. storage standard - it's more like a music playing standard - see the
  208. document for details.)
  209.  
  210.  
  211.  
  212.                                Control Panel
  213.                                ~~~~~~~~~~~~~
  214.  
  215.     The main MultiPlayer window normally sits quietly in the title bar. (If
  216. you don't like it there, move it somewhere else and save the preferences -
  217. it'll stay put wherever you want it.)  However, if you click the zoom
  218. gadget, it will become a control panel.  The F1 key also performs this
  219. function. If you have a 3-button mouse, the middle button will act the same
  220. as the zoom gadget.  This panel displays a few pieces of information about
  221. the module currently playing, and has some buttons you can use to control
  222. MultiPlayer.
  223.  
  224.     The MultiPlayer control panel is an AppWindow, so you can play modules
  225. by simply dropping their Workbench icons into the MultiPlayer window.  When
  226. you do, the new module (or several modules, if you extended-select them)
  227. replaces the current program, and MultiPlayer starts playing the first
  228. module immediately.  This works basically like selecting modules with the
  229. New button.
  230.  
  231.  
  232. Module box
  233.  
  234.     This box displays the filename of the module currently loaded
  235. (essentially the same as what is displayed in the title bar).  Any 'mod.'
  236. prefixes for Soundtracker/Noisetracker modules will not be displayed.
  237.  
  238.  
  239. Type box
  240.  
  241.     Displays the type of the loaded module (as MultiPlayer sees it).
  242. Simple enough?
  243.  
  244.  
  245. Author box
  246.  
  247.     Displays the name of the person who wrote this module, if MultiPlayer
  248. can glean this information from the module.  Most current module formats
  249. don't have direct facilities for identifying the author - in this case, the
  250. box will just display 'Unknown'.  Soundtracker/Noisetracker modules often
  251. have author names embedded in the instrument list - in this case,
  252. MultiPlayer will try to make a good guess by searching for keywords such as
  253. 'by'.  (If it screws up for some reason, you can always type the module in
  254. hex to find out for sure.)  MED modules have somewhat better support, but
  255. they still don't have a convenient 'author' field - just a catch-all
  256. 'annotation' field, which MultiPlayer processes much the same way as with
  257. Soundtracker modules.  GMOD modules are the only types I know of that
  258. directly support author identification, but they are at the moment few and
  259. far between.  (Let's get with it, OK?  Don't all the wonderful musicians
  260. want to be recognized?)
  261.  
  262.  
  263. Song gadget
  264.  
  265.     This gadget serves two purposes.  First, it displays the name of the
  266. currently loaded module or song as recorded in the module itself.  For
  267. example, with Soundtracker/Noisetracker modules this gadget will display
  268. the song name as recorded in the first 20 bytes of the file.  Many module
  269. formats don't have built-in name fields - in this case, the box will just
  270. display 'Unknown.'
  271.  
  272.     For most types of modules, which support only one song per module, this
  273. gadget will serve no purpose other than displaying the song name - clicking
  274. on it will do nothing.  However, some module formats (such as GMODs) allow
  275. several independent songs to be contained in a single module (for example,
  276. to save memory by using the same instruments on several songs).  In that
  277. case, this gadget will cycle through the available songs in the module.
  278. You can also change songs using the left and right arrow keys.
  279.  
  280.  
  281. Volume slider
  282.  
  283.     This slider controls the volume of the currently playing module.
  284. Minimum volume is all the way to the left; maximum is all the way to the
  285. right. This feature doesn't work with all types of modules, but it works
  286. with the most popular types.
  287.  
  288.     The current master volume, balance, and speed settings are saved with
  289. MultiPlayer's Preferences, so when MultiPlayer starts up they will be set
  290. to whatever they were set to last time you saved MultiPlayer's preferences.
  291.  
  292.  
  293. Balance slider
  294.  
  295.     This slider adjusts the balance by scaling the left and right volumes
  296. separately.  When the slider is all the way to the left, only the left
  297. channels will be played; when it is all the way to the right, only the
  298. right channels will be played.  Normally it's in the center, where both
  299. sides play with equal volume.  Like the volume control, this feature
  300. doesn't work with every type of module MultiPlayer supports.
  301.  
  302.  
  303. Balance Reset button ('=')
  304.  
  305.     The small button labeled with an equals sign resets (equalizes) the
  306. Balance slider, setting it back to the center position.
  307.  
  308.  
  309. Speed slider
  310.  
  311.     This slider can be used to fast-forward through a module.  The normal
  312. position is to the far left; moving the slider right will speed it up. This
  313. gadget isn't meant for controlling the module's normal playing speed - for
  314. that, use the speed control in the Settings window.
  315.  
  316.  
  317. Jump buttons ('<<' and '>>')
  318.  
  319.     For module types that support sequence jump, these buttons will
  320. instantly jump one sequence forward or backward in the module.
  321.  
  322.  
  323. New button
  324.  
  325.     This button displays the file requester and lets you select any number
  326. of modules.  The new list of modules replaces the current program, if there
  327. was one.  The first module in the list (or a random module, if you have
  328. selected random playing) will be started.  If you select a directory but
  329. don't select a file (leave the "File" string gadget blank), MultiPlayer
  330. scans the directory and adds everything in that directory to the program.
  331.  
  332.  
  333. Play button
  334.  
  335.     Starts (or restarts) the currently loaded module at the beginning.
  336.  
  337.  
  338. Cont button
  339.  
  340.     Starts or continues playing a module that was previously stopped but
  341. not unloaded.  If the module type supports the continue feature, the module
  342. will continue playing where it left off.  Otherwise it will start again
  343. from the beginning.  If you have selected the 'Fade...' checkbox in
  344. Preferences, and the module type supports volume control, the music will
  345. fade in gradually instead of just starting instantly.
  346.  
  347.  
  348. Stop button
  349.  
  350.     Stops the current module without unloading it.  Audio channels and
  351. interrupts are freed while a module is stopped, so you don't have to exit
  352. MultiPlayer completely if you want to run some other program that needs the
  353. audio hardware.  If you have selected the 'Fade...' checkbox in
  354. Preferences, and the module type supports volume control, the music will
  355. fade out gradually instead of stopping instantly.  If the module type
  356. supports restart, you can restart it where it left off by pressing the Play
  357. button.
  358.  
  359.  
  360. Eject button
  361.  
  362.     Stops and unloads the currently loaded module, and frees all memory and
  363. other resources that the module was using.
  364.  
  365.  
  366. Prev button
  367.  
  368.     Loads and plays the previous module in the program list.  If you have
  369. selected random play, this button simply loads another module in the list,
  370. at random.  This button does the same thing as pressing the up arrow key in
  371. the MultiPlayer window.
  372.  
  373.  
  374. Next button
  375.  
  376.     Loads and plays the next module in the current program list.  If you
  377. have selected random play, this button does basically the same thing as the
  378. Prev button - picks another module at random.  This is the same as pressing
  379. the down arrow key in the MultiPlayer window.
  380.  
  381.  
  382. Program, Prefs, Settings, and Info buttons
  383.  
  384.     These buttons toggle on or off some of MultiPlayer's other
  385. commonly-used windows.  They can also be controlled with the functions keys
  386. F2-F5 (respectively).
  387.  
  388.  
  389.  
  390.                               Program Window
  391.                               ~~~~~~~~~~~~~~
  392.  
  393.     The program window displays a list of all the modules in the current
  394. module 'program'. You can select modules from the list to load and play
  395. immediately by simply double-clicking on their names.  You can also build
  396. and rearrange your program using this window.  You get this window by
  397. pressing the 'Program' button on the main window's control panel, or by
  398. pressing the F2 keys in the MultiPlayer window, or by simply clicking the
  399. right mouse button while any of MultiPlayer's windows are active.  Note
  400. that this window doesn't cause the main control panel to "freeze" - you can
  401. still watch and use it while this window is open.  In fact, all of
  402. MultiPlayer's windows (even the file requester) work this way.  (I'm tired
  403. of Macinsquash-like modal requesters and such that only let you do one
  404. thing at a time.)
  405.  
  406.     Depending on the play mode selected in the Preferences window, when one
  407. module is finished, another module will be automatically loaded and played.
  408. (This only applies on modules that can detect repeat - most do, but on
  409. those that don't, unless you manually set an end time in the Settings
  410. window, the module will just play forever until you explicitly tell
  411. MultiPlayer to go to the next module.)  With random play, a different
  412. module will be randomly chosen.  There is no limit to the number of modules
  413. you can have in a program, and modules in the program can be located in
  414. many different directories - MultiPlayer will remember the location of each
  415. module.
  416.  
  417.     The Program window is an AppWindow, so you can add modules by simply
  418. dropping their icons into this window. This window works slightly
  419. differently from the main Multiplayer window, however.  When you drop icons
  420. into this window, the behavior is the same as if you had selected the
  421. modules with the 'Add' button:  The new modules are added to the end of the
  422. current program list (instead of replacing the current program), and
  423. whatever is currently playing remains unaffected.
  424.  
  425.     Besides the module listing, this window contains several buttons that
  426. allow you to manipulate the module list.  These are described below:
  427.  
  428.  
  429. Play button
  430.  
  431.     This button does basically the same thing as double-clicking on a
  432. module name in the program list.  It simply loads and starts playing the
  433. currently selected module.
  434.  
  435.  
  436. Current button
  437.  
  438.     Pressing this button will set the currently selected module to the
  439. currently playing module.
  440.  
  441.  
  442. Add button
  443.  
  444.     This button works much the same way as the 'New' button on the main
  445. window - it brings up the file requester and allows you to select modules.
  446. However, it doesn't cause the previous program to be cleared when you
  447. finish, and it doesn't start playing a new module immediately.  If you
  448. select a directory without selecting a filename, MultiPlayer will scan that
  449. directory and add all the files in it to the program.
  450.  
  451.  
  452. Del button
  453.  
  454.     This button deletes the currently selected module in the program list.
  455. If this module is currently playing, it doesn't stop the module immediately
  456. - the module continues playing until you select a different module.  The
  457. next module in the program will immediately become the currently selected
  458. module, so you can delete a range of modules by repeatedly clicking the Del
  459. button.
  460.  
  461.  
  462. Top, Up, Down, and Bot buttons
  463.  
  464.     These buttons allow you to rearrange the modules in the program.  They
  465. work on the currently selected module, and their meanings should be
  466. reasonably obvious.
  467.  
  468.  
  469. Load button
  470.  
  471.     Brings up the file requester so you can load a previously saved program
  472. from disk.  The newly loaded program will replace the current program.
  473.  
  474.     Note that you can also load saved programs from the regular module
  475. requester - programs are recognized just like modules, and programs
  476. selected this way will automatically be loaded and run.  (You could even
  477. put the name of another program file at the bottom of the first one, and
  478. chain programs together!)
  479.  
  480.  
  481. Save button
  482.  
  483.     Brings up the file requester and lets you save the current program to a
  484. disk file.  You can then load it again later through the Load gadget or
  485. using any method normally used to select modules - the file requester,
  486. Workbench extended-select when starting MultiPlayer, or CLI arguments.
  487. (See the 'Startup' for details on starting MultiPlayer.)
  488.  
  489.  
  490. Clear button
  491.  
  492.     Clears the entire current program list.  As with the 'Del' button, it
  493. does not stop any currently playing module.
  494.  
  495.  
  496. Sort button
  497.  
  498.     Sorts the entire current program list alphabetically.  Handy if you
  499. like to use random play (and thus don't really care about the play order)
  500. and you'd like a nice neat module listing.
  501.  
  502.  
  503. Program, Prefs, Settings, and Info buttons
  504.  
  505.     These buttons toggle on or off some of MultiPlayer's other
  506. commonly-used windows.  They can also be controlled with the functions keys
  507. F2-F5 (respectively).
  508.  
  509.  
  510.     If you want to create or modify saved program files yourself, just take
  511. a look at one of the files MultiPlayer generates - it's a simple text file.
  512. Lines starting with 'DIR' denote changes of directory - all filenames after
  513. that until another 'DIR' keyword will be looked for in that directory.
  514. Lines that start with a tab character (make sure they remain tab
  515. characters, and don't get converted to spaces!) contain the settings
  516. information for the module on the previous line.  I won't explain the
  517. format exactly, but it shouldn't be too hard for you to figure out if you
  518. want to.  (You can also look at the source code...)
  519.  
  520.  
  521.  
  522.                             Preferences Window
  523.                             ~~~~~~~~~~~~~~~~~~
  524.  
  525.     MultiPlayer's built-in Preferences window can be opened by clicking on
  526. the 'Prefs' button in the main or Program window, or by pressing F3 in any
  527. window.  It contains a few options which you can use to tailor MultiPlayer
  528. to your own preferences.  The gadgets are described below:
  529.  
  530.  
  531. Font buttons and displays
  532.  
  533.     These two buttons allow you to choose the font used for displaying the
  534. gadgets and other imagery used in MultiPlayer's windows.  Pressing either
  535. button brings up a standard ASL font requester (which is asynchronous, of
  536. course - it doesn't freeze up MultiPlayer while it's displayed).  The text
  537. and number gadgets beside each button show the currently selected font.
  538.  
  539.     The Main font is the font used to display almost all of MultiPlayer's
  540. gadgetry: essentially everything except the ListView gadgets in the Program
  541. window and the Information window.  For those, the List font is used
  542. instead.  The Main font can be any font you like, but the List font must be
  543. a fixed-width font.  For the window title bars, the screen's default is
  544. used.  (For the Workbench screen, this is selected by the System Text
  545. setting in the Font Preferences program.)
  546.  
  547.  
  548. Play gadget
  549.  
  550.     Use this gadget to tell MultiPlayer what to do when it gets to the end
  551. of one module.  When 'In sequence' is selected, entire program is played,
  552. in order, one module after another, and the sequence starts over at the
  553. beginning after the last module is played.  If you select 'Through sequence
  554. once', the entire sequence is played only once, then the player stops. In
  555. random play, a module plays once and then another is randomly selected. In
  556. 'once' mode, the song is played only once, then is ejected and MultiPlayer
  557. becomes idle.  In 'over and over' mode, anything you select is played
  558. forever until you tell MultiPlayer to start a different module.  (In these
  559. last two modes, you can still use the 'Next' and 'Prev' buttons in the main
  560. window to change modules; MultiPlayer just doesn't change by itself.)
  561.  
  562.  
  563. Show gadget
  564.  
  565.     This cycle gadget allows you to select the type of display you want to
  566. appear in the main window's title bar while a module is playing.  In Clock
  567. mode, a clock appears displaying the amount of time this module has been
  568. playing in minutes and seconds.  In Sequence mode (this has no relation to
  569. the 'in sequence' mode in the 'Play' gadget), on NoiseTracker or similar
  570. modules that play sequences of blocks, the current sequence number and the
  571. number of sequences in the song is displayed.  (On modules that don't
  572. support this, the clock is displayed instead.)  You can tell MultiPlayer to
  573. display the current sequence number either starting from 0 and ending at
  574. length-1, as most tracker programs display sequence numbers, or starting
  575. from 1 and ending at (length), which is the more 'natural' way of counting.
  576. Selecting the 'Nothing' option in this gadget will leave you with a clean,
  577. simple, unadulterated title bar.
  578.  
  579.  
  580. Hot key string gadget
  581.  
  582.     By default, this string gadget is empty and MultiPlayer behaves like a
  583. normal application.  However, you can enter a Commodities-style hotkey name
  584. into this gadget.  (Make sure you press Return in the gadget after changing
  585. the string!)  MultiPlayer will then activate that key as a hot key which
  586. you can use to open the main MultiPlayer control panel at any time.  When a
  587. hot key is active, clicking the control panel's close gadget closes all of
  588. MultiPlayer's windows, but does not terminate MultiPlayer or stop playing
  589. music.  You can use this too keep MultiPlayer hidden in the background,
  590. without using any screen space at all.
  591.  
  592.  
  593. Spectrogram, Note Scroller, StereoScope, and QuadraScope checkboxes
  594.  
  595.     Use these gadgets to toggle MultiPlayer's various "flashy windows" on
  596. and off.  These windows are described in detail later.  They can also be
  597. toggled with the F6-F9 keys (respectively).
  598.  
  599.  
  600. Fade... checkbox
  601.  
  602.     If this checkbox is activated, whenever you press the 'Play' or 'Stop'
  603. gadgets in the main control panel (or press the spacebar), the music
  604. gradually fades in and out rather than abruptly starting or stopping.
  605. This will only happen on modules that support volume control.
  606.  
  607.  
  608. Continue program on error checkbox
  609.  
  610.     If this is selected, if MultiPlayer encounters an error while trying to
  611. load or play a module in the program, instead of simply stopping dead, it
  612. moves on to the next program in the list, as requested with the Play gadget.
  613.  
  614.  
  615. Save program with prefs checkbox
  616.  
  617.     If this checkbox is activated, MultiPlayer does two things differently
  618. than it normally does.  First, when you save the preferences, not only are
  619. the preferences saved as usual, but the currently loaded program is also
  620. saved in ENV: and ENVARC: in a file called "MultiPlayerProgram".  (It saves
  621. identical files into both directories.)  Second, when MultiPlayer starts
  622. up, if it sees that you have this option set, and you haven't specified any
  623. other modules or programs in the startup options, it automatically loads
  624. this program, without starting it.  This way, if you generally only keep
  625. one program around, this option provides an easy way to always load it
  626. automatically without worrying about any startup options or anything.  Even
  627. if you have this option selected, you can still load and save other
  628. programs normally through the Program window.
  629.  
  630.  
  631. Nasty Audio checkbox
  632.  
  633.     If this option is turned on, MultiPlayer always allocates audio
  634. channels the very highest priority possible, so that no other
  635. (system-friendly) programs can grab the audio channels and play beeps or
  636. speech or other noises on top of the music.  It also prevents some problems
  637. with certain ill-behaved programs (especially terminal programs) that
  638. allocate one or two audio channels on startup and never free them until
  639. they exit, even though they aren't using them the whole time.  Without this
  640. option set, MultiPlayer will typically "be nice" and let the program keep
  641. its channels, and only play music out the other channels - probably not
  642. quite what you wanted.  Setting Nasty Audio allows MultiPlayer to grab
  643. those channels.
  644.  
  645.  
  646. Icon checkboxes
  647.  
  648.     If one of these is activated, MultiPlayer puts an icon on the Workbench
  649. screen which you can drop modules and directories into.  Dropping modules
  650. onto the 'Play' icon erases the old program and starts playing the new
  651. modules immediately.  Dropping modules onto the 'Add' icon simply adds the
  652. new files to the end of the current program, without affecting any module
  653. currently playing.  These icons will remain on the Workbench even if all of
  654. MultiPlayer's windows are closed, or if MultiPlayer's windows are on a
  655. different screen.  Double-clicking on the icon itself will pop up
  656. MultiPlayer.
  657.  
  658.     This feature works only if MultiPlayer can find its own icon on
  659. startup.  You can ensure this by starting MultiPlayer from the Workbench,
  660. or by naming the executable "Player" and having it in the current directory
  661. when you run MultiPlayer from the CLI.
  662.  
  663.  
  664. Save button
  665.  
  666.     Saves the current preferences to the disk file ENV:MultiPlayerPrefs, as
  667. well as to the same file in ENVARC:.  (With a preferences window as simple
  668. as this, I see no real need for separate 'Save' and 'Save Default'
  669. options.)  If the "Keep..." option is enabled, the current program will
  670. also be saved to both ENV: and ENVARC:, as MultiPlayerProgram.
  671.  
  672.     The preferences saved include, as well as the current settings of the
  673. above two gadgets, the positions of all the MultiPlayer windows, including
  674. the file and font requesters.  The next time you run MultiPlayer, the
  675. windows will pop up wherever they were when you saved the preferences. (If
  676. you open an ASL file or font requester and change its size or position, you
  677. must close it before saving the preferences, if you want its new position
  678. and size to be saved.  Nag Commodore about this misfeature, which stems
  679. from a lack of asynchronous functionality in the asl.library.)
  680.  
  681.  
  682. Close button
  683.  
  684.     Does exactly the same thing as the close gadget on the window does -
  685. closes the Preferences window.  It does NOT cause the new preferences to be
  686. activated, as you might expect, because they are already activated:
  687. anything you select gets activated the moment you select it.  (None of
  688. those exclusive Macie dialog boxes, please.)  There is no 'Cancel' gadget
  689. because I figure it's not too difficult to change back any buttons you
  690. accidentally hit.
  691.  
  692.  
  693.  
  694.                               Settings Window
  695.                               ~~~~~~~~~~~~~~~
  696.  
  697.     MultiPlayer's Settings window serves a function very similar to the
  698. Preferences window.  However, there is an important difference.  Instead of
  699. storing settings that apply to MultiPlayer as a whole, it is used to select
  700. options that pertain to individual modules in the program list.  To get it,
  701. click the 'Settings' button in the program window, or press F4 in any of
  702. MultiPlayer's windows.
  703.  
  704.     The Settings window contains a number of gadgets which control how the
  705. currently selected module (not necessarily the currently playing module) is
  706. to be played.  MultiPlayer stores separate settings for each module on the
  707. program list.  When you save the program, the settings for each module are
  708. saved with it.  Not all of the settings are applicable to every type of
  709. module, so some settings gadgets will be disabled for certain modules.
  710.  
  711.  
  712. Module box
  713.  
  714.     This text box displays the name of the currently selected module (the
  715. same as the name displayed under the program list gadget in the Program
  716. window).  This is not necessarily the module that is currently playing -
  717. you can edit the settings for one module while you play another (or while
  718. you're not playing any module).
  719.  
  720.  
  721. Volume, Balance, and Speed gadgets
  722.  
  723.     The gadgets in these two rows complement the corresponding gadgets in
  724. the control panel.  While the controls in the main window control whatever
  725. module is currently playing, these gadgets control the individual modules
  726. in the program.  For example, when you play a given module, the volume at
  727. which it plays is determined by both the master volume setting on the main
  728. control panel, and the volume setting for that specific module defined in
  729. the Settings window.  This allows you to set specific settings for
  730. individual modules, while still being able to control the overall speed,
  731. volume, and balance independently from the main control panel.
  732.  
  733. Note that the Speed gadget in this window works somewhat differently from
  734. the one in the main window.  The main window's Speed gadget is meant to be
  735. basically just for fast-forwarding through a song, while the Speed gadget
  736. in this window allows you to tell MultiPlayer how fast to play this module
  737. normally.  This window also contains two extra buttons, 'PAL' and 'NTSC',
  738. which set the Speed gadget to one of two common playing speeds.
  739.  
  740.  
  741. End box and gadgets
  742.  
  743.     These settings allow you to tell MultiPlayer when to stop a module that
  744. normally doesn't stop by itself, or to make MultiPlayer stop playing the
  745. module before it would normally end.  The text box displays the amount of
  746. time MultiPlayer will let the module play before stopping it, if you've set
  747. an endpoint.
  748.  
  749.     To set a module's endpoint, you must be currently playing the module
  750. you want to change the setting for.  (The Set button will only be activated
  751. if this is the case.)  When the music gets to the point where you would
  752. like it to stop every time you play it, click the Set button.  MultiPlayer
  753. will record the endpoint and, since setting the endpoint implies that you
  754. have reached it, the module will immediately end.  Next time you play that
  755. module, it will stop automatically at that point.  To clear a module's
  756. endpoint, just click the Clear button.
  757.  
  758.  
  759. Filter gadget
  760.  
  761.     This gadget determines how the low-pass filter (and the power LED) is
  762. handled.  Normally it's just set to 'controlled by module', so music
  763. modules can turn it on or off as part of their effects.  However, if a
  764. particular module does things you don't like with the filter, you can force
  765. the filter permanently on or off with this gadget, so the module can no
  766. longer control it.  Of course, this feature works only on module types that
  767. allow MultiPlayer to control the filter.
  768.  
  769.  
  770. Protracker tempo commands
  771.  
  772.     This checkbox is only activated for standard ST/NT/PT modules.  If it
  773. is not set, the Protracker player interprets all speed commands in the
  774. module as NoiseTracker and other older trackers did, and keeps the baseline
  775. frequency at 50Hz (or whatever you set the speed to).  If this checkbox is
  776. set (the default), the newer Protracker tempo commands are enabled.
  777.  
  778.     Basically, this option is here because there is no reliable way to
  779. detect whether a module is using only NoiseTracker speed commands or needs
  780. Protracker tempo commands.  While most modules will work fine on either
  781. setting, some will only play at the correct speed at one setting.  If you
  782. play a module and it suddenly starts going way too slow, or way too fast,
  783. or otherwise plays at an obviously "wrong" speed, try flipping this
  784. checkbox and start the module again.  In general, older modules need this
  785. checkbox to be off, while newer Protracker modules need it on.
  786.  
  787.  
  788. Fade checkbox
  789.  
  790.     If you select this checkbox, and the module supports volume control,
  791. then when the module ends, instead of stopping immediately it will continue
  792. for a couple seconds longer (most likely repeating an earlier part of the
  793. song), gradually fading out.  This is nice for the many modules that just
  794. repeat over and over, and never really end.  With this feature you can make
  795. the "artificial" ending seem a little more natural.
  796.  
  797.  
  798. Current button
  799.  
  800.     Pressing this button will set the currently selected module to the same
  801. as the currently playing module.  Thus, if you are listening to a module
  802. and decide you want to change something about it, you don't have to hunt it
  803. down in the program list - just press this button, and you can immediately
  804. make settings changes to the module you're listening to.
  805.  
  806.  
  807. Close button
  808.  
  809.     This button simply closes the Settings window.  Like the Close button
  810. in the Preferences window, it doesn't actually cause anything else to
  811. happen, because whenever you change anything in the Settings window, the
  812. changes take effect immediately.
  813.  
  814.  
  815.  
  816.                             Information Window
  817.                             ~~~~~~~~~~~~~~~~~~
  818.  
  819.     The Module Information window contains a single read-only ListView
  820. display which contains various miscellaneous information that MultiPlayer
  821. gleans out of the currently playing module.  For module types such as MED
  822. and GMOD which have specific support for some kind of general text string,
  823. that gets displayed here.  For ST/NT/PT modules, this contains the names of
  824. all the instruments (which composers often replace with messages, credits,
  825. and greetings).  The information window can be toggled on or off with
  826. either the Info button on the Program window, or with the F5 key.
  827.  
  828.     If the last instrument used in an ST/NT/PT module contains ASCII text
  829. instead of normal instrument data, it will be displayed here also.  It can
  830. be as long as desired, may contain newline characters, and MultiPlayer will
  831. automatically word-wrap long lines.  (Just for you Maruku...)
  832.  
  833.  
  834.  
  835.                               Flashy Windows
  836.                               ~~~~~~~~~~~~~~
  837.  
  838.     For your viewing pleasure, MultiPlayer contains some little gizmos that
  839. you've probably seen before in Eurodemos and other players.
  840.  
  841.     The Spectrogram window displays a bar graph of the frequencies
  842. currently playing.
  843.  
  844.     The Note Scroller window shows a miniature tracker-like display of the
  845. notes scrolling up the screen.  (You can't read the notes, but if you're
  846. using MultiPlayer you're probably wanting to listen to music, not read it,
  847. right?)  This works only on Protracker-type modules.
  848.  
  849.     The StereoScope window shows an oscilliscope-like view of the sound
  850. coming out of each channel.  The QuadraScope is basically the same thing as
  851. the StereoScope, except it has a separate display for each of the four
  852. channels. (You can have both the StereoScope and the QuardraScope active at
  853. the same time if you want.)
  854.  
  855.     All four windows can be toggled on and off from the Preferences window.
  856. Each also has a function key that works from any of the windows. You can
  857. toggle the Spectrogram window with F6, the Note Scroller with F7, the
  858. StereoScope with F8, and the QuadraScope with F9.
  859.  
  860.     All "flashy" window updating is done in a separate task with a priority
  861. of -5, so turning on these windows should not degrade system performance at
  862. all.  However, this means that the windows will stop updating temporarily
  863. when the system is heavily loaded.
  864.  
  865.  
  866.  
  867.                             Keyboard Shortcuts
  868.                             ~~~~~~~~~~~~~~~~~~
  869.  
  870.     Several keyboard shortcuts are available from any MultiPlayer window
  871. (except the file requester).  Most of these have been mentioned before in
  872. this document, but they are listed all together here as well.  These keys
  873. are listed below:
  874.  
  875. ESC key
  876.  
  877.     Terminates MultiPlayer immediately (a shortcut for the close gadget on
  878. the main window.
  879.  
  880. F1
  881.  
  882.     Opens and closes (or, rather, zooms and unzooms) the main control
  883. panel.  Same as the middle mouse button or the zoom gadget on 2.0.
  884.  
  885. F2 key
  886.  
  887.     Toggles the Program window (opens it, or closes it if it was already open).
  888.  
  889. F3 key
  890.  
  891.     Toggles the Preferences window.
  892.  
  893. F4 key
  894.  
  895.     Toggles the Settings window.
  896.  
  897. F5 key
  898.  
  899.     Toggles the Module Information window.
  900.  
  901. F6 key
  902.  
  903.     Toggles the Spectrogram window.  (Also toggles the Spectogram item in
  904. the Preferences window.)
  905.  
  906. F7 key
  907.  
  908.     Toggles the Note Scroller window.
  909.  
  910. F8 key
  911.  
  912.     Toggles the StereoScope window.
  913.  
  914. F9 key
  915.  
  916.     Toggles the Note Scroller window.
  917.  
  918. Spacebar
  919.  
  920.     If a module is currently playing, stops (or pauses) it without
  921. unloading it, just like the 'Stop' button in the main window.  If a module
  922. is loaded but NOT playing, it continues or restarts it, just like the
  923. 'Play' button.
  924.  
  925. Delete key
  926.  
  927.     Unloads ('ejects') the currently loaded module.
  928.  
  929. Up/down arrows
  930.  
  931.     These switch to the previous or next modules in the program list,
  932. respectively.  In random play, these simply select another module at
  933. random.  (These are shortcuts for the 'Next' and 'Prev' buttons in the main
  934. window.)
  935.  
  936. Left/right arrows
  937.  
  938.     For modules that contain more than one song, these select the previous
  939. or next song, respectively (shortcuts for the 'Song' cycle gadget).
  940.  
  941.  
  942.  
  943.                               Startup Options
  944.                               ~~~~~~~~~~~~~~~
  945.  
  946.     When starting MultiPlayer from Workbench, you can extended-select the
  947. icons of as many modules as you want when you start MultiPlayer.  It will
  948. add all of these modules to the program and immediately start playing the
  949. first one (or a random selection, if you have selected random play in your
  950. saved preferences).  Additionally, you may set certain default parameters
  951. in the ToolTypes field of MultiPlayer's Workbench icon; these are described
  952. later in this section.
  953.  
  954.     MultiPlayer supports a full set of 2.0-style command-line options.  You
  955. can get a brief list of them by typing 'Player ?' on the command line.  To
  956. get a brief description of the parameters, enter another question mark
  957. ('?') and press return at the prompt.
  958.  
  959.     Following is a description of these command-line arguments:
  960.  
  961.  
  962. DIR (synonym: DIRECTORY)
  963.  
  964.     The first argument on the command line (or the argument preceded by
  965. the DIR keyword, if you use the keyword) tells MultiPlayer what directory
  966. to go to the first time it displays the file requester.  This is also where
  967. it will look for modules you specify on the command line (see below) if you
  968. don't specify full pathnames for them.  Using this option to specify the
  969. directory where everything else comes from can save you some typing if you
  970. specify several modules that reside in the same directory on the command
  971. line.
  972.  
  973.  
  974. PLAY/M (synonym: MODULES/M)
  975.  
  976.     The second argument (if you don't explicitly use the DIRECTORY or
  977. PLAY/MODULES keywords) begins a list of modules to put into MultiPlayer's
  978. program list on startup and start playing immediately.  MultiPlayer imposes
  979. no limitations on the number of modules you can specify using this keyword,
  980. although AmigaDOS command lines are currently limited to 256 characters.
  981. After MultiPlayer starts up, instead of showing the file requester
  982. immediately, it will load and begin playing the first module in the program
  983. list (or a randomly selected module, if you have selected random playing in
  984. your saved Preferences).  Program list files act the same way as modules,
  985. so you can specify a program file to load and start initially instead of a
  986. list of modules.
  987.  
  988.  
  989. PROG/K (synonym: PROGRAM/K)
  990.  
  991.     You can use this keyword followed by the name of a program file as an
  992. alternative to the PLAY option.  If you use this option, MultiPlayer will
  993. load the named program file on startup and just go idle, rather than
  994. starting the first module immediately as it would if you used the PLAY
  995. keyword.  To start the program, just hit the "Next" or "Prev" gadgets in
  996. the main window (or just hit the up or down arrow keys in any of the
  997. MultiPlayer windows).
  998.  
  999.     Note that, apparently due to a bug in 2.04, if you specify the PROG
  1000. keyword without giving a directory name as the first option, the PROG
  1001. keyword and the program get put together and interpreted as a module name
  1002. for the MODULE keyword!  Therefore, instead of "Player prog mus:blah", just
  1003. use "Player mus: prog blah".
  1004.  
  1005.  
  1006. SCREEN/K
  1007.  
  1008.     You can use this parameter to tell MultiPlayer to open its windows on a
  1009. screen other than the Workbench (or default) screen.  Just supply the name
  1010. of the public screen as this parameter, and MultiPlayer will try to use it
  1011. for all its windows.  The named public screen must already be open.
  1012.  
  1013.  
  1014. NOREQUEST/S
  1015.  
  1016.     If you specify the switch, MultiPlayer will not display the file
  1017. requester immediately after it loads, even if you don't specify any modules
  1018. to start playing.  If you don't specify any modules, MultiPlayer will
  1019. simply sit idle until you tell it to do something.
  1020.  
  1021.  
  1022. NOWINDOW/S
  1023.  
  1024.     This switch causes MultiPlayer to load and run without opening its main
  1025. window.  If you specify modules to start playing, MultiPlayer will play
  1026. them as usual, but you won't see any visual indication that MultiPlayer is
  1027. running.  If you have activated a hot key in MultiPlayer's saved
  1028. preferences, you can later open the control panel with it.  You can also
  1029. open the window through MultiPlayer's ARexx port, assuming you haven't
  1030. turned that off as well.
  1031.  
  1032.  
  1033. NOREXX/S
  1034.  
  1035.     If you specify this switch, MultiPlayer will not open its ARexx port.
  1036. I don't know what you'd really need this option for, but it's there...
  1037.  
  1038.  
  1039. NODETACH/S
  1040.  
  1041.     If you specify this switch, MultiPlayer will not automatically detach
  1042. itself from the CLI process.  In this case, unless you RUN it, it will keep
  1043. your CLI window until you quit MultiPlayer.
  1044.  
  1045.  
  1046.     If you run MultiPlayer from the Workbench, it will search through the
  1047. ToolTypes array in its own icon for parameters which are roughly equivalent
  1048. to the CLI parameters described above.
  1049.  
  1050. DIR (synonym: DIRECTORY)
  1051. PROG (synonym: PROGRAM)
  1052. SCREEN
  1053.  
  1054.     These ToolTypes act exactly like the corresponding CLI arguments.
  1055. Simply enter one of these ToolType labels, then an equals ('=') sign, then
  1056. the appropriate text.  For example, to load the program "Mus:DefaultProg"
  1057. on startup, add the ToolType "PROG=Mus:DefaultProg".
  1058.  
  1059. REQUEST
  1060. WINDOW
  1061. REXX
  1062.  
  1063.     These ToolTypes perform the same functions as the similarly named CLI
  1064. arguments, but instead of simply being flags,they are YES/NO ToolTypes. For
  1065. example, to prevent MultiPlayer from opening the main window on startup,
  1066. enter "WINDOW=NO" into the ToolTypes.
  1067.  
  1068.  
  1069.  
  1070.                                 ARexx Port
  1071.                                 ~~~~~~~~~~
  1072.  
  1073.     Whenever MultiPlayer is running, there is an ARexx port available
  1074. called "RXTRACKER" which you can send various commands to.  MultiPlayer's
  1075. ARexx port is designed to be (mostly) compatible with the program RxTracker
  1076. by Dominic Giampaolo.  In addition, it has several extended features, and
  1077. of course you can use it to play all the different kinds of modules
  1078. MultiPlayer understands.
  1079.  
  1080.     If MultiPlayer runs into an error when trying to load or play a module,
  1081. it generally returns an error code of 10 to the ARexx program.  When any
  1082. error occurs, a descriptive error string is saved and you can get it with
  1083. the LASTERROR command.
  1084.  
  1085.     A listing of the ARexx commands MultiPlayer understands follows:
  1086.  
  1087.  
  1088. LOAD    <filename>
  1089.  
  1090.     Loads a module into memory from disk.  It is generally a good idea to
  1091. supply a complete pathname, since MultiPlayer looks for the module starting
  1092. at whatever directory the file requester last happened to be looking at.
  1093. This command does not start the module playing.  If you want to start
  1094. playing immediately, you don't have to use this command at all - you can
  1095. simply supply a filename on the PLAY command and it will load and start
  1096. playing immediately.  Note that unless you tell MultiPlayer to load a
  1097. program file, this command won't affect the program list at all - the ARexx
  1098. port in general operates independently of the standard user interface.  If
  1099. you explicitly tell MultiPlayer to load a program file using this command,
  1100. then the new program list will replace the old one.
  1101.  
  1102.  
  1103. PLAY    [<filename>] [<songnumber>]
  1104.  
  1105.     Starts playing a module.  If you supply the filename, MultiPlayer stops
  1106. any module currently playing and tries to load the specified module from
  1107. disk, like the LOAD command.  If you don't supply the filename, MultiPlayer
  1108. plays (or re-plays from the start) an already-loaded module.  (If no module
  1109. is loaded and you don't specify a filename, MultiPlayer returns error code
  1110. 5 and otherwise does nothing.)  For modules with more than one song, you
  1111. can supply the song number to play.  Songs are numbered starting at zero.
  1112. If you don't supply a song number, the first one (song zero) is assumed.
  1113.  
  1114.  
  1115. STOP
  1116.  
  1117.     Stops playing any module that is currently playing without unloading
  1118. the module.  You can then restart it later with PLAY or CONTINUE.
  1119.  
  1120.  
  1121. UNLOAD
  1122.  
  1123.     Stops and unloads any currently loaded module.
  1124.  
  1125.  
  1126. CONTINUE
  1127.  
  1128.     Tries to restart a stopped module at the position it was at before the
  1129. STOP command was given.  If the module has never been started, it simply
  1130. starts from the beginning.  If the module was already playing, it does
  1131. nothing.  If the module type doesn't support restarting, MultiPlayer
  1132. returns error code 5 and does NOT start the module - you can then use PLAY
  1133. to start again from the beginning if you want, or else chew out the user
  1134. for playing weird module formats.
  1135.  
  1136.  
  1137. OPENWINDOWS
  1138.  
  1139.     Opens the main MultiPlayer window.  It will be opened in the small
  1140. title-bar zoom state, and none of MultiPlayer's other windows will be
  1141. opened with it.  If the window was already open, this command does nothing.
  1142. It returns an error if the window can't be opened.  Remember that while the
  1143. window is open the user can use it to change modules and such, possibly
  1144. messing up your perfectly organized and timed ARexx-controlled playing
  1145. sequences.
  1146.  
  1147.  
  1148. CLOSEWINDOWS
  1149.  
  1150.     Closes all MultiPlayer windows, if any were open.  MultiPlayer remains
  1151. active, and continues playing any modules it was already playing.
  1152.  
  1153.  
  1154. LASTERROR
  1155.  
  1156.     Returns an error message describing the last error that occurred that
  1157. had to do with the ARexx port.  (Errors that the user causes by
  1158. manipulating the window do not affect this.) You'll have to have 'options
  1159. results' turned on for this to work, and the error will appear in the
  1160. 'RESULT' variable.
  1161.  
  1162.  
  1163. QUIT
  1164.  
  1165.     Causes MultiPlayer to terminate immediately.
  1166.  
  1167.  
  1168.  
  1169.                                  Messages
  1170.                                  ~~~~~~~~
  1171.  
  1172.     This section lists most of the error or warning messages MultiPlayer
  1173. can produce.  Look here if you have trouble deciphering the meaning of one.
  1174.  
  1175.  
  1176. "Not enough chip memory"
  1177.  
  1178.     Tracker-style modules generally must be loaded into one big continuous
  1179. chunk of chip memory.  Therefore, even if the Workbench (or some other
  1180. program) says you have enough memory, it may not have one big enough chunk.
  1181. Close some windows, exit some programs.  If all else fails, reboot and try
  1182. fresh.
  1183.  
  1184.  
  1185. "Not enough memory"
  1186.  
  1187.     You really are getting low.  MultiPlayer doesn't normally need too much
  1188. non-chip memory, since modules are always loaded into chip memory.  If you
  1189. get this message, it means you don't have much memory of ANY kind
  1190. available.  Better free up something quick.
  1191.  
  1192.  
  1193. "Required memory occupied"
  1194.  
  1195.     You will only get this message from non-relocatable AMOD or GMOD
  1196. modules.  It means that the module has a specific address it must be loaded
  1197. into, but part or all of the required block of memory is already in use.
  1198. Free up as much memory as possible and try again.  If most of your memory
  1199. is free and you still can't load it, chances are there's some little
  1200. allocated fragment that some program has forgotten about that's still
  1201. sitting in the required area.  Your best bet is to reboot and try on a
  1202. fresh system.  If you have more than 512K of chip memory, try running my
  1203. program 'ChipMunch' (included with the official distribution of
  1204. MultiPlayer) just after you reboot to keep programs out of the commonly
  1205. used areas.
  1206.  
  1207.  
  1208. "Unknown module type"
  1209.  
  1210.     MultiPlayer doesn't recognize the file you selected as one of the
  1211. module types it knows.  Either this isn't a music module, or it's one that
  1212. it doesn't know how to handle.  If it is a music module that MultiPlayer
  1213. doesn't know about, send me the module and player/interface code, and it
  1214. should make it into the next version of MultiPlayer.
  1215.  
  1216.  
  1217. "Corrupt module"
  1218.  
  1219.     MultiPlayer recognized the module, but it didn't look right for some
  1220. reason.  Maybe it's a module written with an incompatible version of the
  1221. music program, or maybe the module itself got munched somehow.
  1222.  
  1223.  
  1224. "Error playing module"
  1225.  
  1226.     A general catch-all.  This error usually is displayed as a result of
  1227. error reports from initialization routines of individual players.  It
  1228. generally means that the module loaded fine, but the player had trouble
  1229. playing it.  Sometimes it means the same thing as "Corrupt module", or it
  1230. might mean that the player ran out of memory but was too stupid to tell
  1231. MultiPlayer about it specifically.
  1232.  
  1233.  
  1234. "Can't load module"
  1235.  
  1236.     The requested file was not found, or there was a disk error while
  1237. reading it.  If you get this message after selecting a file from the file
  1238. requester, chances are the disk is corrupt (in this case AmigaDOS should
  1239. have already given you a requester saying so), or the file may be open for
  1240. writing from some other program.
  1241.  
  1242.  
  1243. "Directory not found"
  1244.  
  1245.     Somehow you managed to tell MultiPlayer to load something from a
  1246. directory that doesn't exist.  Maybe you moved the directory somewhere
  1247. else, or forgot an Assign somewhere.  This usually only happens with ARexx
  1248. commands or loaded programs.
  1249.  
  1250.  
  1251. "Audio hardware in use"
  1252.  
  1253.     MultiPlayer can't allocate the audio hardware through the audio.device.
  1254. This probably means that some other music editor or player is currently
  1255. running.  Find the culprit program and close it.  If all else fails, reboot
  1256. and try again.
  1257.  
  1258.  
  1259. "No CIAB timers available"
  1260.  
  1261.     MultiPlayer generally uses one of the two timers on CIA (Complex
  1262. Interface Adapter) B for timing its music.  However, other programs like to
  1263. use these also.  In particular, (I believe) one of the timers may be in use
  1264. if the serial port is in operation.  Other than that, music programs are
  1265. generally the biggest consumers of CIAB timers.  Make sure no other music
  1266. player or composer programs are running, and try closing terminal programs
  1267. or other programs that use the serial port.
  1268.  
  1269.  
  1270. "Please decompress this module"
  1271.  
  1272.     It is unlikely that you will ever get this message, but if you do, it
  1273. means that (a) the module MultiPlayer is trying to load is compressed
  1274. somehow (MultiPlayer had to use the xpkmaster.library to decompress it),
  1275. and (b) it is an AMOD or GMOD module that must load at an absolute address,
  1276. and (c) MultiPlayer would have to re-load the module rather than just
  1277. copying it to its final position because the memory the module occupied
  1278. initally overlapped the required module address.  If you don't quite
  1279. follow, don't sweat - just decompress the module.
  1280.  
  1281.  
  1282. "Can't exit at this point"
  1283.  
  1284.     You tried to exit MultiPlayer while an ASL file or font requester was
  1285. open.  The asl.library file requesters currently don't provide any friendly
  1286. way for the client (MultiPlayer in this case) to close the file requester
  1287. before the user clicks on one of the gadgets or the close box.  Thus,
  1288. MultiPlayer must refuse to exit until you close those file requesters
  1289. manually.
  1290.  
  1291.  
  1292.  
  1293.                              Supported Formats
  1294.                              ~~~~~~~~~~~~~~~~~
  1295.  
  1296. MultiPlayer currently supports the following module types:
  1297.  
  1298.         15-instrument SoundTracker modules (most anyway)
  1299.         31-instrument SoundTracker/NoiseTracker 1.3D modules
  1300.  
  1301.         Protracker 1.0-1.1B modules
  1302.  
  1303.         SoundTracker 2.6 modules
  1304.  
  1305.         NoiseTracker 1.3D packed modules (with or without the embedded player)
  1306.  
  1307.         NoisePacker 2.01 modules
  1308.  
  1309.         Digital Sound Studio modules
  1310.  
  1311.         StarTrekker 1.2 AM/FM modules (Extra '.NT' file required)
  1312.  
  1313.         MED 3.00-3.21 and OctaMED/OctaMED Pro modules
  1314.                 Note: Modules (MMD0, MMD1) only - not "Song&Samples" files.
  1315.  
  1316.         Oktalyzer 4- and 8-channel modules
  1317.                 Uses my own 8-channel play engine.  8-channel modules will
  1318.                 be slightly higher quality on a 68020+ processor.
  1319.  
  1320.         SoundFX V1.3 executable modules (Player V2.2)
  1321.                 Will probably ONLY work with this version, since it does
  1322.                 some run-time patching to make it play under MultiPlayer.
  1323.  
  1324.         Future Composer 1.3 ('SMOD') and 1.4 ('FC14') modules
  1325.  
  1326.         JamCrackerPro 1.0a modules
  1327.  
  1328.         SoundMonitor 2.0 modules
  1329.  
  1330.         SidMon 2.1 modules
  1331.  
  1332.         Delta Music modules (two versions)
  1333.  
  1334.         Mark II modules
  1335.  
  1336.         Dave Whittaker modules
  1337.  
  1338.         Face The Music modules (DO NOT COMPRESS!)
  1339.                 This is very kludgy at best - you must have "PlayFTM:" ASSIGNed
  1340.                 to the PlayFTM program file.  (Didn't know you could ASSIGN
  1341.                 to a file?  Now you do!)  The procedure involves loading the
  1342.                 module, the external player, and then the module again.  Ack!
  1343.  
  1344.         Generic embedded-player modules that start with something like
  1345.                         jmp init(pc)
  1346.                         jmp music(pc)
  1347.                         jmp end(pc)
  1348.                 (Such as NoiseTracker 1.3 packed w/player modules)
  1349.  
  1350.         AudioMaster III sequenced 8SVX sounds (mono only)
  1351.  
  1352.         'XMOD', 'AMOD', and 'GMOD' formats described in 'Formats.doc'
  1353.  
  1354.  
  1355.     Although sequenced 8SVX sounds are technically only sampled sound
  1356. files, they have some music capability and look promising.  Besides, the
  1357. player also plays non-sequenced 8SVX sounds, so you can also play your
  1358. movie clips and such with MultiPlayer.  (I'm not sure if AudioMaster III is
  1359. the only program that currently supports sequenced 8SVX files, but it's the
  1360. only one I've seen so far.) Stereo is currently not supported - sorry, I'll
  1361. get to that eventually.
  1362.  
  1363.  
  1364.  
  1365.                               Version History
  1366.                               ~~~~~~~~~~~~~~~
  1367.  
  1368. 1.32    (R5, 14-Sep-92)
  1369.         Fixed a rather embarrassing bug that caused MultiPlayer to crash when
  1370.             a program was loaded as a module. (thx Jon Grout)
  1371.         Added Yet Another Compatibility Hack (YACH) to the Protracker player (ptsplay)
  1372.             to deal with old modules that stored repeat start in bytes instead of words.
  1373.         Added "Nasty Audio" feature in Prefs window, which makes MultiPlayer allocate
  1374.             auido channels at maximum priority: won't allow "beeps" and such above
  1375.             the music, and avoids conflicts with certain ill-behaved terminal programs.
  1376.  
  1377. 1.31    (R4, 23-Jul-92)
  1378.         Major source code cleanup; code no longer uses regargs.
  1379.         Eliminated overlay support (in preparation for a future metamorphosis...).
  1380.         Added NoisePacker 2.01 support.
  1381.         Fixed two SoundMonitor player bugs. (thx Teijo Kinnunen)
  1382.         Fixed infinite loop bug caused by "continue on error"
  1383.             feature. (thx Jeff Saffold)
  1384.         Fixed minor Guido bug that appeared in the program window.
  1385.         Added OctaMED Pro 4- and 8-channel module support. (thx Teijo Kinnunen)
  1386.         Added Cont gadget in control panel; Play gadget now restarts song. (sug Klinosky)
  1387.         Added Digital Sound Studio support (thx Jeff Booker)
  1388.         Fixed a nasty several-version-old bug causing hangs by certain combinations
  1389.             of actions in the Program window (especially load/save buttons).
  1390.  
  1391. 1.30    (R3, 25-May-92)
  1392.         GNU-ized and released with full source code.
  1393.  
  1394. 1.21    (R2, unreleased)
  1395.         Icon 8-colorized.  (thx Barry McConnell)
  1396.         The "Protracker tempo commands" option is now on by default.
  1397.         Protracker player now uses the audio.device NotePlayer, so all Protracker
  1398.             playing is now completely system-friendly.
  1399.         Some windows rearranged significantly.
  1400.         Other minor bug fixes and enhancements.
  1401.  
  1402. 1.20    (R1, 5-May-92)
  1403.         Finally got around to bumping the minor revision counter. :-)
  1404.         This version does NOT work under 1.3 or earlier versions of Kickstart.
  1405.         Added SoundTracker 2.6 support.
  1406.         Added NODETACH command-line switch.
  1407.         Added command-line extended help (displayed if you type "MultiPlayer ?"
  1408.             and then enter "?" again at the template prompt).
  1409.         Module and Program file requesters now remember their current paths separately.
  1410.             (Side effect: it is now possible to show both file requesters at once!)
  1411.         File and font requester positions and sizes are now saved in
  1412.             MultiPlayer's preferences.
  1413.         Rearranged the function keys yet again.  (THIS time it _should_ be for good...)
  1414.         Added Module Information window.
  1415.             (Displays instruments, scolltexts, even MaruSampleTexts...)
  1416.         Redrew MultiPlayer's icon.  (About time...)
  1417.         Added AppIcon support.  (You can drop modules into it even when MultiPlayer's
  1418.             windows are closed or on another screen.)
  1419.         Changed speed control range on the main panel to be more useful.
  1420.             (The normal position is to the far left, and it can go VERY fast.)
  1421.         Added sequence jump controls to the main panel.
  1422.         Added balance reset gadgets in the main and settings windows.
  1423.         Added support for user-selectable fonts in the windows.
  1424.         Added "continue program on error" preferences option.
  1425.         Added "Through sequence once" option in Play mode in Preferences.
  1426.  
  1427. 1.17    (28-Feb-92)
  1428.         Fixed a serious bug in Guido (the user interface system) that sometimes
  1429.             caused crashes under 2.0.
  1430.         Fixed a tempo bug in the Protracker player.
  1431.         Modules in the program list are now played by double-clicking them.
  1432.             (lets you delete and do other things on them without playing them.)
  1433.         Added Settings window.  (Get to it from the Program window.)
  1434.         Rearranged the function key assignments yet again.
  1435.             (Sorry - they should stay the same for a while now.)
  1436.         MultiPlayer can now read parameters from its ToolTypes for options when
  1437.             started from Workbench.
  1438.         Added volume control to Oktalyzer 8-channel player.
  1439.         Added Commodities support under 2.0 - only one copy of MultiPlayer
  1440.             gets run at once, and you can pop it up with a hot key.
  1441.         Two of the ARexx port's command names have changed: OPENWINDOW and CLOSEWINDOW
  1442.             are now OPENWINDOWS and CLOSEWINDOWS.
  1443.         Added "Save program with preferences" option (in the Preferences window).
  1444.         Changed the random number generator, hopefully for the better.
  1445.         Note: The 1.3 support in this version of MultiPlayer is very minimal.  The
  1446.             next version will probably not support 1.3 at all.  Going, going...
  1447.  
  1448. 1.16    (8-Feb-92)
  1449.         Fixed a serious bug in the DeltaMusic player.
  1450.         Save Prefs now snapshots both states of main window.
  1451.         Flashy window updates now run in a separate low-priority task.
  1452.         Upgraded MED 3.20 player to 3.21, and added Continue support.
  1453.             (Thanks Mr. Kinnunen!)
  1454.         Added (very kludgy) Face The Music support.
  1455.             (See the "Supported Formats" section for how to use it.)
  1456.         Added PROG keyword to command line options.
  1457.             (Lets you load a program file without starting immediately.)
  1458.         Fixed Mark II player.
  1459.         Protracker player now supports CIA tempo commands.
  1460.         Created Quadrascope and Note Scroller windows.
  1461.         Right and middle mouse buttons now work in all windows.
  1462.         LED (and filter) no longer get turned on at inappropriate times.
  1463.         Added directory scanning feature to program list manager.
  1464.             (If you "add" a directory to the program, MultiPlayer scans
  1465.             it and adds its contents to the program.)
  1466.         Added volume, balance, and speed controls to main window.
  1467.  
  1468. 1.15    (17-Jan-92)
  1469.         Upgraded MED 3.11 player to MED 3.20.
  1470.             (The MED player also now supports multiple songs).
  1471.         Added OctaMED 1.00 support.
  1472.         Fixed a small bug in author search routine.
  1473.         Fixed SidMon player bug.
  1474.         Added Spectrogram and Scope windows.
  1475.         Created non-overlaid version (Player.nov) for registered release.
  1476.  
  1477. 1.14    (6-Jan-92)
  1478.         Internal pseudo-release.
  1479.  
  1480. 1.13    (1-Jan-92)
  1481.         Added Oktalyzer 8-channel support using my own 8-channel audio engine.
  1482.             (Never did find a real Oktalyzer 8-channel play routine.)
  1483.  
  1484. 1.12    (29-Dec-91)
  1485.         Protracker support added by replacing the NoiseTracker player with the
  1486.             (similarly modified) Protracker 1.1B player.  I haven't detected
  1487.             any backward incompatibilities with NoiseTracker modules, but
  1488.             tell me if you find any.
  1489.         Oktalyzer 4-channel player finally tested and fixed.
  1490.                 (Yep, it didn't work at all.  Sorry...)
  1491.  
  1492. 1.11b   (19-Dec-91)
  1493.         Control panel clock/sequence display now always matches title color under 2.0.
  1494.         Fixed minor event-handling bug.
  1495.  
  1496. 1.11a   (12-Dec-91)
  1497.         Fixed bug in 8SVX player.
  1498.         Window positions are now saved with preferences.
  1499.  
  1500. 1.11    (10-Dec-91)
  1501.         Repeat detection bug in ST/NT player fixed.
  1502.         Program and preferences windows now save their positions while closed.
  1503.         Enhanced author name detection.
  1504.         Added middle-mouse-button zoom feature.
  1505.         Added 'Nothing' option to the show mode in preferences.
  1506.         Improved Delta Music module recognition.
  1507.  
  1508. 1.10    (18-Nov-91)
  1509.         Right mouse button in the main window has changed functions:
  1510.             Under 1.3, it zooms the window (since there's no zoom gadget)
  1511.             Under 2.0, it shows the program window (like the Help or F1 key)
  1512.         File requester is now asynchronous (other windows remain active).
  1513.         Control panels are now fully 1.3 compatible.
  1514.             (Although they still don't look as nice as in 2.0...)
  1515.         Keyboard shortcuts now supported in all control panels.
  1516.         Added public screen support.
  1517.         Added "play once" feature.
  1518.         DMA delays now use scanline waits instead of delay loops.
  1519.         Re-opening sub windows now closes them rather than bringing them to the front.
  1520.         Added AppWindow support for 2.0.
  1521.  
  1522. 1.01    (8-Nov-91)
  1523.         Added 'Sort' button in program window.
  1524.         Fixed a serious bug in GMOD player.  (Only serious if you have GMOD modules...)
  1525.         Enhanced author name recognition for ST/NT modules.
  1526.  
  1527. 1.00    (5-Nov-91)
  1528.         This is basically a rewrite of most of the program.
  1529.             (I'm not listing all the additions - there are way too many.)
  1530.         Major changes and additions to Formats.doc.
  1531.         Music no longer cuts off when file requester is displayed.
  1532.         Removed built-in code compression.  (Maybe I'll put it back in later.)
  1533.         Audio device now allocated while playing music.
  1534.         Fixed SoundFX player bug which caused crashing on advanced processors.
  1535.         Players now use longer DMA delays (normally 300) only on fast processors.
  1536.             (Wouldn't want to bog down you poor ol' 68000 users would we?)
  1537.         Major rewrite of player selection code.
  1538.         CIAB interrupts now defer to software interrupts to avoid hogging
  1539.             CPU time in a high-priority interrupt.
  1540.  
  1541. 0.95a   (6-Sep-91)
  1542.         Fixed bug where song position appeared when no module was playing.
  1543.         Fixed ST/NT player bug for modules with negative song repeat positions.
  1544.  
  1545. 0.95    (27-Jul-91)
  1546.         Added song position indicator for ST/NT and MED modules.
  1547.         Added code to turn low-pass filter off by default (will soon be selectable).
  1548.         Added Messages section to the documentation.
  1549.         Fixed window position so it snuggles right up next to the screen gadgets.
  1550.  
  1551. 0.94a   (26-Jul-91)
  1552.         Fixed player window height on pre-2.0 operating systems.
  1553.         Increased delay loop (ugh!) in NoiseTracker player for faster processors.
  1554.         Fixed song repeat bug in NoiseTracker player.
  1555.         Hacked NoiseTracker player to play old 15-instrument modules.
  1556.         Fixed memory trashing bug in NoiseTracker player.
  1557.             (I hate cleaning up someone else's code!)
  1558.  
  1559. 0.94    (23-Jul-91)
  1560.         Uses one of the CIAB timers for timing rather than the VBlank interrupt.
  1561.         Finally uses Workbench 2.0 ASL file requester if available.
  1562.         Added MED 3.xx modules, removed MED 2.xx songs.
  1563.  
  1564. 0.93    (3-Jul-91)
  1565.         Workbench 2.0 compatible (although some modules may not be).
  1566.  
  1567. 0.92    (7-Jun-91)
  1568.         Added 'AMOD' absolute loading module format described in 'Formats.doc'.
  1569.         Added 'GMOD' general module format described in 'Formats.doc'.
  1570.         Added NoiseTracker 1.3D packed (with player) modules.
  1571.         Added StarTrekker 1.2 AM synthesized modules.
  1572.         Updated the SoundTracker/NoiseTracker player.
  1573.             (New player comes from NoiseTracker 1.3D)
  1574.  
  1575. 0.91    (29-Apr-91)
  1576.         Added 'XMOD' format described in 'Formats.doc'.
  1577.         Removed "unknown" module formats (turned those modules into XMOD's)
  1578.  
  1579. 0.90    (27-Apr-91)
  1580.         First preliminary release.  Nothing fantastic.
  1581.  
  1582.  
  1583.  
  1584.                               Contact Address
  1585.                               ~~~~~~~~~~~~~~~
  1586.  
  1587.     I tend to move around a great deal, so mail sent directly to me
  1588. sometimes has a hard time catching up.  If you want mail to reach me (it
  1589. may take a while, but it WILL reach me), send it to this address:
  1590.  
  1591.         Bryan Ford
  1592.         8749 Alta Hills Circle
  1593.         Sandy, UT 84093
  1594.  
  1595.     I can be reached more quickly (for the time being anyway) on the phone
  1596. or through the electronic mail address below:
  1597.  
  1598.         (801) 944-1990
  1599.         baford@peruvian.utah.edu
  1600.  
  1601.  
  1602.